发布软件包

pub 软件包管理器 不仅用于使用其他人的软件包，它也允许你与全世界分享你的软件包。如果你有一个实用的项目并且希望其他人能够使用它，可以使用 dart pub publish 命令。

观看以下视频，了解构建和发布软件包的概览。

请记住，发布的软件包是永久性的。一旦你发布了软件包，用户就可以依赖它。一旦他们开始依赖它，移除该软件包会破坏他们的项目。为了避免这种情况，pub.dev 政策 不允许取消发布软件包，除了极少数情况。

你总是可以上传新版本的软件包，但旧版本仍然可供尚未升级的用户使用。

对于失去关联性或缺乏维护的已发布软件包，请将其标记为已停止维护。

发布软件包时，请遵循 pubspec 格式和软件包布局结构中找到的约定。为了简化软件包的使用，Dart 要求遵循这些约定。这些约定包含一些在链接指南中指出的例外情况。调用时，pub 会指出你可以进行哪些更改，以使你的软件包在 Dart 生态系统中更好地工作。

除了这些约定之外，你还必须遵守以下要求

• 在你的软件包中包含一个 LICENSE 文件。我们推荐 BSD 3 条款许可证，这是 Dart 和 Flutter 团队通常使用的许可证。但是，你可以使用任何适合你软件包的许可证。

• 验证你具有合法权利重新分发作为软件包一部分上传的任何内容。

• gzip 压缩后，将软件包大小保持在 100 MB 以下。如果软件包太大，可以考虑将其拆分成多个软件包，使用 .pubignore 文件移除不必要的内容，或者减少包含的资源或示例数量。

• 你的软件包只能依赖于默认 pub 软件包服务器上的托管依赖项和 SDK 依赖项（sdk: flutter）。这些限制确保将来可以找到和访问你的软件包的依赖项。

• 拥有一个 Google 账号。Pub 使用 Google 账号来管理软件包上传权限。你的 Google 账号可以关联 Gmail 地址或任何其他电子邮件地址。

Pub 使用一些文件的内容来为你的软件包在 pub.dev/packages/<你的软件包名称> 上创建页面。以下文件会影响你的软件包网页的内容。

README.md

此文件包含你软件包网页上的主要内容。文件内容应使用 Markdown 进行标记。要了解如何编写出色的 README，请参阅编写软件包页面。

CHANGELOG.md

如果存在，此文件会在你的软件包网页上填充一个单独的标签页。开发者可以直接从 pub.dev 读取你的更改。文件内容应使用 Markdown 进行标记。

pubspec.yaml

此文件在你软件包网页的右侧填充有关软件包的详细信息。文件内容应遵循 YAML 约定。这些详细信息包括描述、主页等。

你可以使用认证发布者（推荐）或独立的 Google 账号发布软件包。使用认证发布者具有以下优势

• 你的软件包的使用者知道发布者域名已通过认证。
• 你可以避免在 pub.dev 上显示你的个人电子邮件地址。相反，pub.dev 会显示发布者域名和联系地址。
• pub.dev 网站会在搜索页面和单个软件包页面上，在你的软件包名称旁边显示一个认证发布者徽章 。

要创建认证发布者，请按照以下步骤操作

1. 前往 pub.dev。

2. 使用 Google 账号登录 pub.dev。

3. 从右上角的用户菜单中选择 Create Publisher。

4. 输入你想与发布者关联的域名（例如，dart.dev）。

5. 点击 Create Publisher。

6. 在确认对话框中，选择 OK。

7. 如果出现提示，完成验证流程。这将打开 Google Search Console。

   • 添加 DNS 记录后，可能需要几个小时才能在 Search Console 中反映更改。
   • 验证流程完成后，返回步骤 4。

使用 dart pub publish 命令首次发布你的软件包或将其更新到新版本。

已发布的软件包包含软件包根目录下的所有文件，但以下情况除外

• 任何隐藏的文件或目录。它们的名称以点（.）开头。
• 在 .pubignore 或 .gitignore 文件中列出要忽略的文件和目录

要为 git 和 dart pub publish 使用不同的忽略规则，请创建一个 .pubignore 文件来覆盖给定目录中的 .gitignore 文件。如果一个目录同时包含 .pubignore 文件和 .gitignore 文件，则 dart pub publish 忽略该目录的 .gitignore 文件。.pubignore 文件的格式与 .gitignore 文件的格式相同。

为避免发布不需要的文件，请遵循以下做法

• 删除任何不想包含的文件，或将其添加到 .pubignore 或 .gitignore 文件中。
• 上传软件包时，检查 dart pub publish --dry-run 命令显示将发布的文件列表。如果该列表中出现任何不需要的文件，请取消上传。

要测试 dart pub publish 将如何工作，你可以执行一次模拟运行（dry run）

dart pub publish --dry-run

使用此命令，dart pub 执行以下任务

1. 验证你的软件包遵循 pubspec 格式和软件包布局约定。

2. 显示它打算发布的所有文件。

以下示例展示了测试发布一个名为 transmogrify 的软件包

Publishing transmogrify 1.0.0
    .gitignore
    CHANGELOG.md
    README.md
    lib
        transmogrify.dart
        src
            transmogrifier.dart
            transmogrification.dart
    pubspec.yaml
    test
        transmogrify_test.dart

Package has 0 warnings.

准备好发布软件包时，移除 --dry-run 参数

dart pub publish

使用此命令，dart pub 执行以下任务

1. 验证你的软件包遵循 pubspec 格式和软件包布局约定。

2. 验证 git status 是干净的。如果 git 中跟踪的文件有未提交的更改，则发出警告。

3. 显示它打算发布的所有文件。

4. 将你的软件包上传到 pub.dev。

你的软件包成功上传到 pub.dev 后，任何 pub 用户都可以在其项目中下载或依赖它。

例如，如果你刚刚发布了你的 transmogrify 软件包的 1.0.0 版本，那么另一个 Dart 开发者就可以在他们的 pubspec.yaml 中将其添加为依赖项

dependencies:
  transmogrify: ^1.0.0

pub.dev 网站会检测软件包支持哪些平台，并在软件包页面上显示这些平台。pub.dev 的用户可以按平台过滤搜索结果。

要更改生成的支持平台列表，请在 pubspec.yaml 文件中指定支持的平台。

发布第一个版本的软件包后，你可以通过 GitHub Actions 或 Google Cloud 服务账号配置自动化发布。要了解更多关于自动化发布的信息，请查阅将软件包自动化发布到 pub.dev。

在开发软件包时，考虑将其发布为预发布版本（prerelease）。预发布版本在以下情况下很有用：

• 你正在积极开发软件包的下一个主版本。
• 你希望为软件包的下一个发布候选版本寻找 Beta 测试者。
• 软件包依赖于 Dart 或 Flutter SDK 的不稳定版本。

如语义化版本控制中所述，要创建版本的预发布版本，请在版本号后附加一个后缀。例如，要创建版本 2.0.0 的预发布版本，你可能会使用版本 2.0.0-dev.1。稍后，当你发布版本 2.0.0 时，它将优先于所有 2.0.0-XXX 预发布版本。

由于 pub 在可用时偏好稳定版本，因此预发布软件包的用户可能需要更改其依赖项约束。例如，如果用户想测试版本 2.1.0 的预发布版本，他们可能会指定 ^2.1.0-dev.1，而不是 ^2.0.0 或 ^2.1.0。

当你将预发布版本发布到 pub.dev 时，软件包页面会显示预发布版本和稳定版本的链接。预发布版本不影响分析分数，不出现在搜索结果中，也不会替换软件包的 README.md 和文档。

预览版本在满足以下所有条件时很有用

• 软件包的下一个稳定版本已完成。
• 该软件包版本依赖于 Dart SDK 中尚未在稳定版 Dart SDK 中发布的 API 或功能。
• 你知道软件包依赖的 API 或功能是 API 稳定的，并且在到达稳定版 SDK 之前不会改变。

例如，考虑一个 package:args 的新版本，它有一个已完成的版本 2.0.0。它依赖于 Dart 3.0.0-417.1.beta 中的一个功能。然而，Dart SDK 的稳定版本 3.0.0 尚未发布。pubspec.yaml 文件可能如下所示

name: args
version: 2.0.0

environment:
  sdk: '^3.0.0-417.1.beta'

当你将此软件包发布到 pub.dev 时，它会被标记为预览版本。以下截图对此进行了说明。它将稳定版本列为 1.6.0，将预览版本列为 2.0.0。

当 Dart 发布 3.0.0 的稳定版本时，pub.dev 会更新软件包列表，将 2.0.0 显示为软件包的最新（稳定）版本。

如果本节开头的所有条件都满足，请忽略 dart pub publish 发出的以下警告

“对 Dart SDK 的预发布版本有 SDK 约束的软件包本身应作为预发布版本发布。如果此软件包需要 Dart 3.0.0-0 版本，请考虑将软件包作为预发布版本发布。”

如果软件包有认证发布者，该软件包的 pub.dev 页面会显示发布者域名。

对于没有发布者发布的软件包，pub.dev 基于隐私原因不公开发布者信息。Publisher（发布者）字段显示“未认证上传者”。

首次发布软件包的人成为第一个也是唯一获授权上传该软件包新版本的人。

要允许或不允许其他人上传版本，可以

• 在软件包的管理页面上管理授权的上传者：https://pub.dev/packages/<软件包名称>/admin。
• 将软件包转移给认证发布者；发布者的所有成员都有上传权限。

要将软件包转移给认证发布者，你必须是该软件包的上传者，并且是认证发布者的管理员。

将软件包转移给认证发布者

1. 使用 Google 账号登录 pub.dev，该账号必须是软件包的上传者之一。

2. 前往软件包详情页面（例如，https://pub.dev/packages/http）。

3. 选择 Admin（管理）标签页。

4. 输入发布者的名称，然后点击 Transfer to Publisher（转移给发布者）。

为了防止新的软件包使用者在七天窗口期内采用你已发布的软件包版本，你可以在发布后的七天内撤回该软件包版本。撤回的版本可以在撤回后的七天内再次恢复。

撤回并非删除。撤回的软件包版本会显示在 pub.dev 上该软件包版本列表的 Retracted versions（已撤回版本）部分。该软件包版本的详细视图会显示一个 RETRACTED（已撤回）徽章。

在撤回软件包之前，考虑发布一个新版本。撤回软件包可能会对软件包用户产生负面影响。

如果你发布的新版本存在缺失的依赖项约束或宽松的依赖项约束，那么撤回软件包版本可能是唯一的解决方案。发布软件包的新版本并不会阻止版本解析器选择旧版本。该版本可能是 pub 可以选择的唯一版本。撤回带有错误依赖项约束的软件包版本会强迫用户升级其他依赖项或导致依赖项冲突。

但是，如果你的软件包包含一个小错误，你可能不需要撤回该版本。发布一个修复了错误的新版本，并在 CHANGELOG.md 中描述修复的错误。这有助于用户理解发生了什么。发布新版本对软件包用户的干扰较小。

如果一个软件包依赖于后来被撤回的软件包版本，只要该版本存在于依赖软件包的 pubspec.lock 文件中，仍然可以使用该版本。要依赖一个已撤回的特定版本，依赖软件包必须在 pubspec.yaml 文件的 dependency_overrides 部分中指定该版本。

当一个软件包依赖于已撤回的软件包版本时，根据其他可用版本，你有几种迁移方式可供选择。

在大多数情况下，已发布新版本来替换已撤回的版本。在这种情况下，运行 dart pub upgrade <软件包名称>。

如果没有可用的新版本，考虑降级到最新的非撤回版本。你可以通过以下两种方式之一来实现。

1. 使用 pub 工具命令

   1. 运行 dart pub downgrade <软件包名称> 以获取指定软件包的符合 pubspec.yaml 文件中约束的最低版本。

   2. 运行 dart pub upgrade <软件包名称> 以获取最新的兼容且未撤回的可用版本。

2. 在你偏好的 IDE 中编辑 pubspec.lock 文件

   1. 删除带有已撤回版本的软件包的整个条目。

   2. 运行 dart pub get 以获取最新的兼容且未撤回的可用版本。

尽管你可以删除 pubspec.lock 文件并运行 dart pub get，但这不推荐。这可能会导致其他依赖项的版本发生变化。

如果没有满足当前版本约束的替代版本可用，请编辑 pubspec.yaml 文件中的版本约束并运行 dart pub upgrade。

要撤回或恢复软件包版本，首先使用一个 Google 账号登录 pub.dev，该账号是该软件包的上传者或认证发布者管理员。然后前往软件包的 Admin（管理）标签页，在那里可以撤回或恢复最近的软件包版本。

尽管软件包仍然发布，你可以向开发者表明软件包没有进行积极维护。这需要你将软件包标记为已停止维护。

一旦你停止维护一个软件包，该软件包将

• 仍在 pub.dev 上发布。
• 仍在 pub.dev 上可查看。
• 显示一个清晰的 DISCONTINUED（已停止维护）徽章。
• 不会出现在 pub.dev 的搜索结果中。

将软件包标记为已停止维护

1. 使用对该软件包具有上传者或认证发布者权限的 Google 账号登录 pub.dev。

2. 导航到软件包的 Admin（管理）标签页。

3. 要停止维护软件包，选择 Mark "discontinued"（标记为“已停止维护”）。

你还可以推荐一个替代软件包。

1. 在 Suggested replacement（建议替代）字段下，输入另一个软件包的名称。

2. 点击 Update "Suggested Replacement"（更新“建议替代”）。

如果你改变主意，可以随时移除已停止维护的标记。